.\" manual page for gbconv, a command-line gamebook generator
.\" Copyright (C) 2008 Jaromir Hradilek
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation;  with no
.\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" 
.\" A copy  of the license is included  as a file called FDL  in the main
.\" directory of the gbtools source package.
.\"
.TH GBCONV 1 "4 August 2008" "Version 0.7.2"
.SH NAME
gbconv \- a command-line gamebook generator
.SH SYNOPSIS
.B  gbconv
.BR \-t " html"
.RB " [" \-e
.IR enc ]
.RB [ \-o
.IR file ]
.RI [ file ]
.br
.B  gbconv
.BR \-t " xhtml"
.RB [ \-e
.IR enc ]
.RB [ \-o
.IR file ]
.RI [ file ]
.br
.B  gbconv
.BR \-t " latex"
.RB [ \-a | \-b ]
.RB [ \-n
.IR name ]
.RB [ \-e
.IR enc ]
.RB [ \-p
.IR pkgs ]
.RB [ \-o
.IR file ]
.RI [ file ]
.br
.B  gbconv
.BR \-t " troff"
.RB [ \-a | \-b ]
.RB [ \-n
.IR name ]
.RB [ \-o
.IR file ]
.RI [ file ]
.br
.B  gbconv
.BR \-t " ascii"
.RB [ \-w
.IR width ]
.RB [ \-l
.IR lines ]
.RB [ \-W
.IR width ]
.RB [ \-L
.IR lines ]
.br
.RB "                [" \-o
.IR file ]
.RI [ file ]
.SH DESCRIPTION
.B  gbconv
is a gamebook generator written in Ruby, that uses a very simple and
lightweight wiki-like markup and provides conversion to several formats,
including HTML, XHTML, LaTeX, troff or plain text. Having a single source
file, you can easily produce professionally looking printed book,
downloadable PDF file or HTML pages for online reading.
.PP
gbconv is designed to make the game development easier: using warnings, it
lets you know about missing options, unreferenced sections or references
pointing to sections that are not written yet. Generally, warnings can (and
will) appear during the writing process, but should be eliminated when the
work is done.
.PP
The basic usage is to run the script with the input file name as its first
argument. If nothing goes wrong, new HTML document is printed to the
standard output. Otherwise, the relevant warning or error message is
reported to the standard error output.
.SH OPTIONS
.SS General options
.TP
.BI \-t " type" "\fR,\fP \-\-type" " type"
Specify target document
.IR type ;
available options are
.BR html ,
.BR xhtml ,
.BR latex ,
.BR troff " and"
.BR ascii .
When omitted,
.B  html
is used by default.
.TP
.BI \-o " file" "\fR,\fP \-\-output" " file"
Use selected
.I file
instead of the default standard output.
.TP
.BR \-h ", " \-\-help
Display help message and exit.
.TP
.BR \-v ", " \-\-version
Display version information and exit.
.SS html and xhtml related options
.TP
.BI \-e " encoding" "\fR,\fP \-\-encoding"  " encoding"
Specify
.I encoding
of the input source file. When omitted, the
.B UTF-8
codepage is used by default as it is probably most universal option.
Nevertheless, if you use different codepage, you should explicitly specify
it. The
.I encoding
should be in the form that is accepted by W3C. Other popular values include
.BR ISO-8859-1 ,
.BR ISO-8859-2
or
.BR windows-1250 .
See <http://www.iana.org/assignments/character-sets> for the complete list.
.SS latex related options
.TP
.BR \-a ", " \-\-article
Produce a simple document with a subset of a cover page on the beginning of
the first page and without the table of contents.
.TP
.BR \-b ", " \-\-book
Produce a document with a separate cover page and a table of contents; the
default option.
.TP
.BI \-n " heading" "\fR,\fP \-\-toc\-name" " heading"
Specify
.I heading
for the table of contents, which is especially useful for processing
non-English documents. When omitted, `Contents' is used by default.
.TP
.BI \-e " encoding" "\fR,\fP \-\-encoding"  " encoding"
Specify
.I encoding
of the input source file in the form recognized by LaTeX's inputenc
package; supported options are
.BR ascii ,
.BR latin1 ,
.BR latin2 ,
.BR latin3 ,
.BR latin4 ,
.BR latin5 ,
.BR latin9 ,
.BR latin10 ,
.BR decmulti ,
.BR cp850 ,
.BR cp852 ,
.BR cp858 ,
.BR cp437 ,
.BR cp437de ,
.BR cp865 ,
.BR cp1250 ,
.BR cp1252 ,
.BR cp1257 ,
.BR applemac ,
.BR macce ,
.BR next
and
.BR ansinew .
See <http://www.iana.org/assignments/character-sets> for the full
description.
.TP
.BI \-p " packages" "\fR,\fP \-\-packages" " packages"
Specify additional comma-separated LaTeX
.IR packages .
.SS troff related options
.TP
.BR \-a ", " \-\-article
Produce a simple document with a subset of a cover page on the beginning of
the first page and without the table of content.
.TP
.BR \-b ", " \-\-book
Produce a document with a separate cover page and a table of contents; the
default option.
.TP
.BI \-n " heading" "\fR,\fP \-\-toc\-name" " heading"
Specify
.I heading
for the table of contents, which is especially useful for processing
non-English documents. When omitted, `Table of Contents' is used by
default.
.SS ascii related options
.TP
.BI \-w " width" "\fR,\fP \-\-par\-indent" " width"
Specify paragraph indentation. The default value is
.BR 0 .
.TP
.BI \-l " lines" "\fR,\fP \-\-par\-skip" " lines"
Specify number of empty
.I lines
between two paragraphs. The default value is
.BR 1 .
.TP
.BI \-W " width" "\fR,\fP \-\-item\-indent" " width"
Specify list indentation. The default value is
.BR 2 .
.TP
.BI \-L " lines" "\fR,\fP \-\-item\-skip" " lines"
Specify number of empty
.I lines
between two list items. The default value is
.BR 0 .
.SH DOCUMENT TYPES
.TP
.B html
Conversion to HTML 4.01 Strict.
.TP
.B xhtml
Conversion to XHTML 1.0 Strict.
.TP
.B latex
Conversion to LaTeX2e. As a matter of fact, gbconv does not require any TeX
distribution to be actually installed, nor it solves badness in typesetting
(i.e. `underfull \\vbox' etc.). However, it takes care of the LaTeX
reserved characters as well as the replacement of some other symbols with
appropriate glyphs.
.TP
.B troff
Conversion to troff, using
.B ms
document format.
.TP
.B ascii
Conversion to plain text.
.SH MARKUP LANGUAGE
As its input, gbconv accepts a single source file with a simple wiki-like
markup language. The extension
.B .gb
is recommended, but not required.
.PP
The input file structure can be divided into following three independent
parts:
.RB "a " "document header" ,
.RB "an " "introductory part"
.RB "and a " "game part"
(i.e. numbered sections) respectively. With the exception of the header,
each of these parts can be safely omitted\-\-you can therefore use gbconv
to produce ordinary documents, although there are probably better and much
more sophisticated solutions, such as txt2tags; however, gbconv is still a
good choice if you are satisfied with its capabilities and/or you don't
want to learn another markup language.
.PP
.B The document header
provides general information about the document, such as
title, author and year. It must be placed at the very beginning of the file
and is automatically terminated by the first occurrence of a section mark
or the end of file.
.PP
.B The introductory part
is basically everything that is not the game itself nor the document
header, being the right place for preface, acknowledgements, background
story, game rules etc. It begins with the first occurrence of the section
mark and ends with the first numbered section or the end of file.
.PP
.B The game part
is probably the most important as it contains the game itself. Its
beginning is marked with the first occurrence of the numbered section and
it lasts to the end of file.
.SS Document header
.TP
.BI "title: " "document title"
The
.IR "document title" .
This line is obligatory and its omission results in appropriate warning
message.
.TP
.BI "author: " "document authors"
One or more
.IR "document authors" .
This line is obligatory and its omission results in appropriate warning
message.
.TP 
.BI "year: " year
The document
.IR year .
Unlike previous two, this line is completely optional as the current year
is used by default.
.SS Headings
.TP
.BI == " chapter " ==
The
.I chapter
heading.
.TP
.BI === " section " ===
The 
.I section
heading.
.TP
.BI ==== " subsection " ====
The
.I subsection
heading.
.TP
.BI == " N " ==
The numbered section heading, where
.I N
is the positive integer.
.SS Paragraphs
Paragraph is virtually any text consisting of one or more lines, with the
only restriction that non of the lines can begin with the number sign (#),
asterisk (*) or semicolon (;). To separate two paragraphs, simply put one
or more empty lines between them.
.SS Lists
.TP
.BI * " bulleted list item"
Line beginning with asterisk marks the first line of bulleted item and any
following non-empty line is considered as its continuation, unless it
begins with asterisk itself. Similarly to paragraph, bulleted list is
terminated with the first occurrence of empty line. 
.TP
.BI # " numbered list item"
Line beginning with number sign marks the first line of numbered item and
any following non-empty line is considered as its continuation, unless it
begins with number sign itself. Similarly to paragraph, numbered list is
terminated with the first occurrence of empty line. 
.TP
.BI ; " N " : " game option"
Guidepost is a special type of list that can only appear in the game part
and that produces a nice looking list of game options.
.I N
is the positive integer pointing to the respective numbered section.
.SS Typefaces
.TP
.BI ''' bold '''
Bold text.
.TP
.BI '' italic ''
Italic text.
.SS Links
.TP
.BI [ "URI text" ]
External page link, where
.I URI
is the address beginning with
.BR http:// ,
.BR ftp:// ,
.BR mailto:
etc. and
.I text
is the optional description.
.TP
.BI [[ N ]]
Numeral link, where
.I N
is the positive integer pointing to the respective numbered section. Like
guidepost, it can only appear in the game part.
.SH SEE ALSO
.BR gbsplit (1),
.BR latex (1),
.BR pdflatex (1),
.BR groff (1),
.BR groff_ms (7),
.BR ruby (1).
.SH BUGS
To report bugs please visit the appropriate section on the project
homepage: <http://code.google.com/p/gbtools/issues/>.
.SH AUTHOR
Written by Jaromir Hradilek <jhradilek@gmail.com>.
.PP
Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.2 or any later
version published by the Free Software Foundation; with no Invariant
Sections, no Front-Cover Texts, and no Back-Cover Texts.
.PP
A copy of the license is included as a file called FDL in the main
directory of the gbtools source package.
.SH COPYRIGHT
Copyright (C) 2008 Jaromir Hradilek
.PP
This program is free software; see the source for copying conditions. It is
distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.
